Kivonat mintahívások
1. Kivonat metaadatok lekérdezése
POST {{baseURL}}/v1/statement/metadata
http headerek:
x-correlation-id: {{$uuid}}
x-request-id: {{$uuid}}
x-api-key: {{$var1}}
x-jws-signature: {{$var2}}
{
"iban": "HU29120670080010034200100009",
"dateFrom": "2024-01-01",
"dateTo": "2024-01-31",
"consentList": ["1111", "2222"]
}
iban— a lekérdezni kívánt bankszámlaszámdateFrom/dateTo— a keresési időszak (YYYY-MM-DD)consentList— mindig 2 elemű tömb: a számlához tartozó 2 hozzájárulás-azonosító. Egyes aláírás esetén ugyanaz az azonosító kétszer is megadható (pl.[1, 1])
response body - successful
{
"allDocRecordCount": 3,
"documents": [
{
"docId": 2283712,
"genDate": "2024-01-02",
"fileOrigName": "kivonat_2024_01_01.pdf",
"iban": "HU29120670080010034200100009",
"externalId": "2014/0000003"
},
{
"docId": 2283713,
"genDate": "2024-01-03",
"fileOrigName": "kivonat_2024_01_02.pdf",
"iban": "HU29120670080010034200100009",
"externalId": "2014/0000004"
},
{
"docId": 2283714,
"genDate": "2024-01-16",
"fileOrigName": "kivonat_2024_01_15.pdf",
"iban": "HU29120670080010034200100009",
"externalId": "2014/0000005"
}
]
}
2. Kivonat letöltés
POST {{baseURL}}/v1/statement/download
http headerek:
x-correlation-id: {{$uuid}}
x-request-id: {{$uuid}}
x-api-key: {{$var1}}
x-jws-signature: {{$var2}}
{
"docId": 2283712,
"consentList": ["1111", "22222"]
}
docId— a letölteni kívánt kivonat azonosítója (az 1. lépés válaszában szereplődocuments[].docId)consentList— mindig 2 elemű tömb: a számlához tartozó 2 hozzájárulás-azonosító. Egyes aláírás esetén ugyanaz az azonosító kétszer is megadható (pl.[1, 1])
response body - successful
{
"docId": 2283712,
"genDate": "2024-01-02",
"fileOrigName": "kivonat_2024_01_01.pdf",
"iban": "HU29120670080010034200100009",
"externalId": "2014/0000003",
"metaList": [
{
"metaName": "CERTIFIED",
"metaValue": "Y"
},
{
"metaName": "STATEMENT_NO",
"metaValue": "2014/0000003"
}
],
"downloadUrl": "https://s3.eu-central-1.amazonaws.com/statements/284470/kivonat_2024_01_01.pdf?response-content-type=application%2Fpdf&X-Amz-Security-Token=IQoJb3JpZ2luX2Vj...",
"urlExpiresAt": "2024-01-02T08:55:40.067507520Z"
}
A válaszban kapott downloadUrl egy időkorlátos link, amely 1 percig érvényes. A kivonat PDF formátumban a downloadUrl-re küldött GET kéréssel vagy böngészőben történő megnyitással tölthető le. A letöltést a válasz megérkezése után haladéktalanul el kell végezni.
3. Aszinkron folyamat indítása
Az aszinkron letöltés megkezdése előtt szükséges az 1. lépés — metaadat lekérdezés elvégzése. A kért docId értéket a metaadat válasz documents[].docId mezőjéből kell kinyerni.
POST {{baseURL}}/v1/statement/async
http headerek:
x-correlation-id: {{$uuid}}
x-request-id: {{$uuid}}
x-api-key: {{$var1}}
x-jws-signature: {{$var2}}
{
"docId": 2283712,
"consentList": ["1111", "2222"]
}
docId— a letölteni kívánt kivonat azonosítója (az 1. lépés válaszában szereplődocuments[].docId)consentList— mindig 2 elemű tömb: a számlához tartozó 2 hozzájárulás-azonosító. Egyes aláírás esetén ugyanaz az azonosító kétszer is megadható (pl.[1, 1])
response body - 201 Created (új folyamat)
{
"processId": "550e8400-e29b-41d4-a716-446655440000"
}
response body - 200 OK (meglévő aktív folyamat)
{
"processId": "550e8400-e29b-41d4-a716-446655440000"
}
4. Aszinkron folyamat állapot lekérdezése
POST {{baseURL}}/v1/statement/async/status
http headerek:
x-correlation-id: {{$uuid}}
x-request-id: {{$uuid}}
x-api-key: {{$var1}}
x-jws-signature: {{$var2}}
{
"processId": "550e8400-e29b-41d4-a716-446655440000",
"consentList": ["1111", "2222"]
}
processId— a 3. lépésben visszakapott folyamatazonosítóconsentList— mindig 2 elemű tömb: a számlához tartozó 2 hozzájárulás-azonosító. Egyes aláírás esetén ugyanaz az azonosító kétszer is megadható (pl.[1, 1])
response body - feldolgozás folyamatban (IN_PROGRESS)
{
"processId": "550e8400-e29b-41d4-a716-446655440000",
"status": "IN_PROGRESS"
}
response body - sikeres feldolgozás (DONE)
{
"docId": 2283712,
"genDate": "2024-01-02",
"iban": "HU29120670080010034200100009",
"externalId": "2014/0000003",
"fileOrigName": "kivonat_2024_01_01.pdf",
"metaList": [
{
"metaName": "CERTIFIED",
"metaValue": "Y"
},
{
"metaName": "STATEMENT_NO",
"metaValue": "2014/0000003"
}
],
"downloadUrl": "https://s3.eu-central-1.amazonaws.com/statements/async/2283712/550e8400-e29b-41d4-a716-446655440000.pdf?X-Amz-Security-Token=...",
"urlExpiresAt": "2024-01-02T08:31:00.067507520Z",
"documentExpiresAt": "2024-01-03T23:30:00Z",
"processId": "550e8400-e29b-41d4-a716-446655440000",
"status": "DONE"
}
A downloadUrl az urlExpiresAt mezőben jelzett időpontig érvényes (kb. 1 perc) — a letöltést haladéktalanul el kell végezni. Ha a link lejárt, de a státusz még DONE, hívja meg újra a státusz lekérdező végpontot: friss downloadUrl-t és urlExpiresAt értéket ad vissza — egészen a documentExpiresAt időpontig.
A documentExpiresAt lejárta után a folyamat EXPIRED státuszba kerül — ekkor új POST /async folyamatot indítani.
5. Teljes aszinkron folyamat — integrációs példa
Az aszinkron letöltés 3 lépésből áll: folyamat indítása → státusz lekérdezése (polling) → PDF letöltése. Az alábbi ábra a teljes folyamatot mutatja be a lehetséges állapotokkal együtt.
| Státusz | Jelentés | Teendő |
|---|---|---|
IN_PROGRESS | Feldolgozás folyamatban | Várj 2–5 mp-et, majd kérdezz újra |
DONE | Kész, letölthető | GET kérés a downloadUrl-re (1 perc érvényes) |
ERROR | Feldolgozási hiba | errorMessage alapján döntés / újraindítás |
EXPIRED | Dokumentum lejárt | Új folyamat indítása POST-tal |
ERROR válasz példa
{
"processId": "550e8400-e29b-41d4-a716-446655440000",
"status": "ERROR",
"errorMessage": "A hiba leírása (ha rendelkezésre áll)"
}
EXPIRED válasz példa
{
"processId": "550e8400-e29b-41d4-a716-446655440000",
"status": "EXPIRED"
}
Ha ugyanarra a docId-ra egyszerre több kérés érkezik, mindegyik kliens ugyanazt a processId-t kapja vissza — a service nem indít felesleges párhuzamos feldolgozást. Biztonságos a POST végpontot többször meghívni.